One

主题

2025-03-062025-06-26指南指南
2312
10m
Get...

Vite 插件 ​

VitePress 是基于 Vite 进行搭建，因此可以编写 Vite 插件来辅助完成一些在无法在浏览器环境完成的动作，比如在 VitePress 启动后，扫描文档目录下的 Markdown 文件，提取 frontmatter的信息进行分析，或在渲染 Markdown 内容前，对其进行加工。

得益于 Vite 环境，Teek 内置了一些 Vite 插件来执行在 Node 环境才能完成的事情，这些插件分别为：

这些插件已经上传至 NPM 仓库，具体的使用说明可以前往 NPM 查看使用说明，或者访问 Github 仓库，每个插件下都有 README.md文档介绍。

也可以在 Teek 的 配置项中查看这些插件。

Teek 使用 vitepress-plugin-permalink来实现永久链接功能。

如果想要禁用该插件，进行如下配置：

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({vitePlugins:{permalink:false,},});

Teek 默认扫描文档根目录下（.vitepress层级开始）的所有 Markdown 文件，如果希望忽略某些目录，可进行如下配置：

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({vitePlugins:{permalinkOption:{ignoreList:["目录名"],},},});

当希望只扫描指定的目录，可进行如下配置：

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({vitePlugins:{permalinkOption:{path:"guide",},},});

国际化 ​

vitepress-plugin-permalink支持国际化功能，在生成 permalink时，默认会给不同语言文档的 permalink添加语言前缀。

假如存在一个 Markdown 文档 guide.md，frontmatter内容如下：

yaml
---title:guidepermalink:/guide---

国际化目录结构如下；

docs/├─ es/│ ├─ guide.md├─ guide.md

那么在生成 permalink时，es语言下的 guide.md的 permalink为 /es/guide。

配置项 ​

permalinkOption的详细配置项请看 Permalink 配置项。

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({vitePlugins:{permalinkOption:{},},});

vitepress-plugin-sidebar-resolve ​

Teek 使用 vitepress-plugin-sidebar-resolve来实现自动生成侧边栏功能。

在 结构化目录中已经介绍了该插件使用的注意事项，如果想要禁用该插件，进行如下配置：

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({vitePlugins:{sidebar:false,},});

国际化 ​

在国际化的环境下，当把 root 语言（默认语言）的 Markdown 文件放到某个路径下时，vitepress-plugin-sidebar-resolve无法感知到，因此请使用 localeRootDir配置项告诉它，在 国际化特殊场景有说明。

侧边栏初始化格式 ​

配置项 initItems和 initItemsText会影响侧边栏的生成格式，举个例子说明：

假设根目录下有目录名为 guide：

  • 当 initItems为 true，则最终结果为 sidebar:{"/guide": { items: [], collapsed }}
    • 当 initItemsText为 true，则最终结果为 sidebar:{"/guide": { text: "guide", items: [], collapsed }}
    • 当 initItemsText为 false，则最终结果为 sidebar:{"/guide": { items: [] }}
  • 当 initItems为 false，则最终结果为 sidebar:{"/guide": [] }

配置项 ​

sidebarOption的详细配置项请看 SideBar 配置项。

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({vitePlugins:{sidebarOption:{},},});

vitepress-plugin-md-h1 ​

Teek 使用 vitepress-plugin-md-h1来给文章页生成一级标题（假如 Markdown 文档没有设置过一级标题）。

一级标题获取顺序：frontmatter.title>文件名

提示

只在页面加载 Markdown 内容时生成一级标题，并不会真正修改 Markdown 文档内容。

假设一个文档 install.md的 frontmatter内容如下：

yaml
---title:guide---

在页面访问该文档时，页面自动生成一级标题 guide，当把 frontmatter.title去掉后，页面的一级标题变为 install。

如果想要禁用该插件，进行如下配置：

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({vitePlugins:{mdH1:false,},});

配置项 ​

mdH1Option的详细配置项请看 MdH1Option 配置项。

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({vitePlugins:{mdH1Option:{},},});

vitepress-plugin-catalogue ​

vitepress-plugin-catalogue插件会将所有 formatter.catalogue为 true 的文档信息挂载到 themeConfig.catalogues中，Teek 使用该数据来生成目录页。

该插件与 Teek 强绑定，无法像上面的组件一样，通过 vitePlugins.catalogue =false来禁用。

如果想要禁用该插件，只能通过禁用 Teek 主题来实现，配置如下：

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({teekTheme:false,});

如果某个 markdown 文档不想被纳入目录里，则：

yaml
---inCatalogue:false---

配置项 ​

catalogueOption的详细配置项请看 Catalogue 配置项。

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({vitePlugins:{catalogueOption:{},},});

vitepress-plugin-doc-analysis ​

Teek 使用 vitepress-plugin-doc-analysis来实现站点信息和文章页信息功能。

vitepress-plugin-doc-analysis在 VitePress 启动后，扫描所有的 Markdown 文档，然后统计文章数量，文章字数等，最终将分析后的数据挂载到 themeConfig.docAnalysisInfo中。

在首页看到的站点信息、文章页看到的文章字数、预计阅读时间等，都是使用 themeConfig.docAnalysisInfo的数据来构成。

如果不希望某个 Markdown 文档被插件分析，请在该文档 frontmatter配置：

yaml
---docAnalysis:false---

如果想要禁用该插件，进行如下配置：

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({vitePlugins:{docAnalysis:false,},});

关于文章的预计阅读时间的计算，该插件默认 1 分钟内阅读的中文字数为 300，1 分钟内阅读的英文字数为 160，如果认为不合理，可以对其进行修改：

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({vitePlugins:{docAnalysisOption:{cn:400,en:200,},},});

国际化 ​

当处于国际化环境下，插件将不同语言的数据挂载到 locales.[lang].themeConfig.docAnalysisInfo。

配置项 ​

docAnalysisOption的详细配置项请看 DocAnalysis 配置项。

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({vitePlugins:{docAnalysisOption:{},},});

vitepress-plugin-file-content-loader ​

Teek 使用 vitepress-plugin-file-content-loader来构建首页的文章列表和归档页数据，并挂载到 themeConfig.posts中。

该插件本质上将 VitePress 官网的 构建时数据加载功能转为插件，因此具体的介绍说明请前往 VitePress 官网阅读。

为什么设计为插件？

构建时数据加载功能是在访问网站的时候开始执行，如果使用该功能扫描了大量的 Markdown 文档，那么会导致第一次进入页面卡顿，因此基于该功能实现了插件，在项目启动过程完成数据的加载。

该插件与 Teek 强绑定，如果想要禁用该插件，只能通过禁用 Teek 主题来实现，配置如下：

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({teekTheme:false,});

国际化 ​

当处于国际化环境下，插件将不同语言的数据挂载到 themeConfig.posts.locales.[lang]下。

配置项 ​

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({vitePlugins:{fileContentLoaderIgnore:{},},});

vitepress-plugin-auto-frontmatter ​

Teek 使用 vitepress-plugin-auto-frontmatter自动给 Markdown 文档添加 frontmatter。

该插件会直接修改 Markdown 文档的 frontmatter，因此为了安全性考虑，默认是关闭的，如果希望开启，进行如下配置：

ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({vitePlugins:{autoFrontmatter:true,},});

如果开启了该插件，那么 Teek 将会对所有 Markdown 文档的 frontmatter添加如下格式：

yaml
---title:gettingdate:2025-03-03 00:45:16permalink:/pages/eb8f2fcategories:- guide---
  • title为文章的标题
  • date为文章的创建时间
  • permalink为文章的永久链接，采用随机数确保唯一
  • categories为文章的分类，根据目录层级获取

提示

Teek 则不会修改已经存在的数据，判断的规则是比较 key，不比较 value。

如果需要拓展自定义 frontmatter，让 Teek 在生成 frontmatter的时候额外添加其他数据，请使用 transform配置项，具体使用请看 vitepress-plugin-auto-frontmatter的 Example 2和 Example 3。

配置项 ​

autoFrontmatterOption的详细配置项请看 AutoFrontmatter 配置项。

Teek 在 vitepress-plugin-auto-frontmatter的配置项基础上额外添加两个配置项：

  • permalinkPrefix：自动生成 permalink的固定前缀，如 pages、pages/demo，默认为 pages
  • categories：是否自动生成 categories
ts
import{defineTeekConfig } from"vitepress-theme-teek/config";constteekConfig=defineTeekConfig({vitePlugins:{autoFrontmatterOption:{permalinkPrefix:"pages",categories:true,},},});
最近更新